---
title: <media-poster-image>
description: Media Poster Image
layout: ../../../../layouts/ComponentLayout.astro
source: https://github.com/muxinc/media-chrome/tree/main/src/js/media-poster-image.js
---
import SandpackContainer from "../../../../components/SandpackContainer.astro";

**Poster images** give your viewers an idea of the contents of the video you're displaying _before_ they view the video. These images can be something as simple as a specific frame from your video, or, a completely custom designed composition of your choice.

The `<media-poster-image>` component will show your poster image in place of your media _before_ the media has been played. You can also optionally show a _secondary_ placeholder image before the poster has loaded. This is generally useful to prevent layout shifts.

For example, you can show a blurhash that mirrors the colors that will appear within your poster image while your _actual_ poster image loads.

You can either use the `<media-poster-image>` component as a static image on its own, or, add the `slot="poster"` attribute to associate it with the underlying video element for click-to-play.

> This component is reliant on Javascript to load the poster image. If better control or better performance is desired, you can use `<img slot="poster" src="...">` instead. Set a placeholder via the `background-image` CSS property in the `style` attribute.

## With `src`

<SandpackContainer
  editorHeight={290}
  html={`<media-controller>
  <video
    slot="media"
    src="https://stream.mux.com/A3VXy02VoUinw01pwyomEO3bHnG4P32xzV7u1j1FSzjNg/low.mp4"
    playsinline
    muted
  ></video>
  <media-poster-image
    slot="poster"
    src="https://image.mux.com/A3VXy02VoUinw01pwyomEO3bHnG4P32xzV7u1j1FSzjNg/thumbnail.jpg?time=20">
  </media-poster-image>
</media-controller>`}
/>

## With `placeholdersrc` and `src`

<SandpackContainer
  editorHeight={290}
  html={`<media-controller>
  <video
    slot="media"
    src="https://stream.mux.com/A3VXy02VoUinw01pwyomEO3bHnG4P32xzV7u1j1FSzjNg/low.mp4"
    playsinline
    muted
  ></video>
  <media-poster-image
    slot="poster"
    src="https://image.mux.com/A3VXy02VoUinw01pwyomEO3bHnG4P32xzV7u1j1FSzjNg/thumbnail.jpg?time=20"
    placeholdersrc="">
  </media-poster-image>
</media-controller>`}
/>

## Hiding the poster image on play

When your media begins to play back, `media-controller` will be assigned the `mediahasplayed` attribute. Media Chrome default styling will ensure that any `media-poster-image` elements that are a child of `media-controller` are hidden when this attribute is present.
